</> 技術筆記Tech Notes

Serenity Platform 實戰教學:SerGenX 讓中文資料表也能優雅產碼

Serenity 的 sergen 工具很強大,能依資料表與欄位自動產生對應的 Serenity 程式碼。然而當你的資料表或欄位不是英文(如中文)時,問題就來了:欄位名稱會被直接轉成 C# 類別屬性,與 Serenity 產生的 partial class 相互衝突,導致你在重生產與手改之間無止盡循環。為了解決這個痛點,我寫了一個「以翻譯對照表為核心」的生成工具:SerGenX。

它的核心思路是:把「資料庫原始命名」與「程式語意命名」從一開始就切乾淨,透過翻譯對照表,讓生成出來的 C# 類別名與屬性名永遠是你想要的英文或團隊規範命名,從根本排除命名衝突與 partial class 覆寫地獄。

SerGenX 如何解你的痛

  • 命名分離:以「表格翻譯對照表」與「欄位翻譯對照表」將中文(或任何語系)映射為英文的類別與屬性名稱。

  • 穩定生成:生成時僅採用翻譯名稱,避免與 Serenity 的 partial class 命名衝突。

  • 型別正確:同時讀取資料庫的欄位型別、長度/精度、可空、主鍵、Identity/Serial,生成貼近真實結構的模型。

  • 跨資料庫:抽象一層 DbExplorer,現已支援 PostgreSQL;MSSQL 架構就緒,易於擴充。

基本觀念與資料來源

  • 表格翻譯:提供 Schema、原始表名、翻譯後表名、C# 類別名稱、模組名稱。

  • 欄位翻譯:提供原始欄位名、翻譯後欄位名、對應 C# 屬性名稱。

  • 表格定義:由資料字典抓欄位型別、主鍵與自增資訊,確保生成的代碼不僅名稱正確、也具備正確的結構語意。

範例結構(概念示意):

  • TableTranslation:承載 SchemaName、OriginalTable、TranslatedTable、CSharpClassName、ModuleName 等屬性,作為表格的命名橋樑。

  • Explorer(以 PostgreSQL 為例):能列出需生成的表格、查詢表格/欄位翻譯、回傳表格定義(欄位、主鍵、identity)。

典型使用流程

  1. 設定連線:提供資料庫連線字串。

  2. 掃描名單:從翻譯對照表取得要生成的表格清單(Schema + 表名)。

  3. 取翻譯:讀出每個表格與欄位對應的英文命名(類別名、屬性名)。

  4. 取定義:讀出欄位型別、PK、可空、長度與精度、identity。

  5. 輸出程式碼:產出遵循命名規範的 Serenity 模組程式碼(或你自訂的模板),與平台生成的 partial class 互補不衝突。

帶來的改變

  • 不再為中文欄位名焦頭爛額:一律透過翻譯對照表轉為乾淨英文化命名。

  • 避免手改地獄:生成結果與平台產物界線清晰,不互相覆寫。

  • 可治理、可演進:調整翻譯表即可重新生成,快速回應命名規範更新。

  • 跨團隊一致性:命名標準集中治理,產出一致,降低上手成本。

適用情境

  • 資料庫歷史命名非英文,且短期內無法改名。

  • 想用 Serenity 生態,但又要保持乾淨的 C# 命名與產碼節奏。

  • 多語系、多團隊協作,需要以同一份翻譯對照表驅動一致輸出。

接下來可以怎麼做

  • 建立與維護翻譯對照表(表格與欄位)作為團隊命名真相來源。

  • 先以 PostgreSQL 導入;如用 MSSQL,按同樣介面補上資料探索查詢即可。

  • 將 SerGenX 納入 CI,讓模型與命名變更可回溯、可重現。

  • 擴充模板,輸出 DTO、Row、Form、Columns、Repository、Endpoint 或前端型別。

如果你也卡在中文欄位與 Serenity 產碼衝突的泥淖,SerGenX 提供一條乾淨、可治理、可持續的出路。告訴我你的資料庫與目標輸出,我可以協助設定翻譯對照表與最佳化產碼流程。